#####################
BibTeX mode for Alpha
#####################

This document describes features of Bib mode and the BibTeX menu, which 
were written to simplify the use and maintenance of BibTeX citation 
database files.

Bib Mode
========

Bib mode is entered when you open a file with a '.bib' suffix, or 
when select the mode explicitly from the modes menu.  In Bib mode,

 A BibTeX menu is added to the menubar.  Commands available from this 
  menu are summarized in the next section below.
       
 Selecting 'Mark File' in the Marks menu, "{}" on the sidebar, will 
  add an index mark for the cite-key of each entry in the bib file.

  Marks are added in order of appearance in the file.  To order them 
  alphabetically, use the "Sort Marks:Alphabetically" command on the 
  Bibtex menu.

 Key words in Bib files are automatically colorized.

 Double-clicking on an abbreviation string with the command key held 
  down ("command-double-clicking") will move the cursor to the definition 
  of that abbreviation.

 Command-double-clicking on the cite-key of a "crossref" field will 
  move the cursor to the referenced entry.


BibTeX menu
===========

Here's a description of the commands available from the BibTeX menu:
(key bindings are indicated where available)

BibTeX interaction
------------------

Bibtex		Switch to the BibTeX application (launching it if necessary).
 
Template insertion
------------------

Entries > 	Insert a template for any of the various BibTeX bibliography 
			entry types (as in Tex mode).
    
			By default, only the required fields an the entry are included in 
		    the template.  This can be customized as described below.
		    
		    Choosing "Custom Entry" lets you pick the fields to be included
		    from a list of all fields.

Fields > 	Insert a template for any of the various BibTeX bibliography 
			data fields.
		    
			Choosing "Custom Field" inserts a template without a pre-written 
			field name.
					    
			Choosing "Multiple Fields" lets you pick the a number fields to 
			be included at once.

Entry Navigation, etc.
----------------------
   
Select Entry	Select (highlight) the current entry (in which the cursor sits), 
			    allowing the entry to be easily moved, copied or deleted.
			    (Ctl-Shift-B)
   
Next Entry		Jump to the top of the next entry.
 				(Ctl-Shift-N)
   
Prev Entry		Jump to the top of the previous entry.
 				(Ctl-Shift-P)
   
Format Entry	Reformat the current entry in a standard form, with data 
			    fields indented and aligned, and data-field delimiters 
			    made uniform.
			    (Ctl-Shift-L)
			    
				Afterwards, Alpha jumps forward to the next entry, so you 
				can keep hitting Ctl-Shift-L to reformat a number of entries 
				in a row.
				
				The format may be customized using the formatting flags 
				and variables in the flags menu ("" on the sidebar).
				
Copy Cite Key	Copy the cite key for the current entry to the clipboard

Sorting and Searching
---------------------

Search Entries	Search for entries that match a given regular expression.
 				(Ctl-Shift-M)
   
Search Fields	Search for entries in which a particular field matches a 
			    regular expression.
			    (Ctl-Shift-F)
				
				Entries found in a search will be copied to a new window 
				(the default) or back into the original buffer, replacing 
				the previous contents of the buffer; this is controlled by 
				the "overwriteBuffer" mode flag.
    
Sort by >		Sort the database by one of various criteria...
 
	Cite Key			Sort by the citatation key
	
	First Author, Year	Sort by first or last author, and secondarily by year
	Last Author, Year
	
	Year, First Author	Sort by year, and secondarily by first or last author
	Year, Last Author 
 
				The "overwriteBuffer" mode flag also controls whether the 
				sorted database is written back to the original buffer or into 
				a new one.
    
Sort Marks >	

	Alphabetically	Sort the index marks on the marks menu alphabetically.
	
	By Position		Sort the index marks by the position of the entry.
	
Other
-----

Count Entries		Report the total number of entries, as well the number
					of entries of each type. 

Format All Entries	Reformat the current entry and all subsequent entries to
					end of the file.
					
					You can interrupt this by hitting the "Cmd-." key


Mode Flags and Variables
========================

The behavior of the Bibtex menu may be controlled using by setting the 
various flags and variables in the flags menu ("") on the sidebar.  
These are...

For Entry Formatting
---------------------

alignEquals 	Line up the "=" signs for all fields when reformatting

entryBraces		Use curly braces to delimit entries (otherwise parentheses 
				are used).

fieldBraces		Use curly braces to delimit field values (otherwise 
				quotation marks are used).

zapEmptyFields 	Remove optional fields if they're empty.
	
				
fillColumn		The maximum width of each line in the field value.				

indentString	Define the indentation string for field names.

stdAbbrevs		Define standard abbreviations (which we avoid surrounding 
				with delimiters) that do not appear in @string entries.
				
				By default, the three-letter English month names are included.

For Sorting and Searching
--------------------------

overwriteBuffer		Allow sorts and searches to replace the original window 
					contents. (Otherwise they are written to a new window.)
    
		Note:	The contents of a ".bib" file, will never be overwritten by 
				a search, since entries are typically lost.
				 	
				A ".bib" file _can_ be overwritten by a sort, since no 
				entries are lost.

descendingYears		Sort by year in descending order (most recent to oldest)

markStrings			Include @string definitions in the marks menu.

segregateStrings	Collect all @string definitions together at the top
					of the file in sorts.  (Otherwise sort alphabetically)

				
Key Bindings
============

Most of these functions (except template insertion) are also bound to 
keystrokes.  The standard bindings are

    Ctl-Shift-N     next entry
    Ctl-Shift-P     previous entry

    Ctl-Shift-B     select entry   
    Ctl-Shift-L     format entry

    Ctl-Shift-M     search entries
    Ctl-Shift-F     search fields

            tab     next tab stop      (as in TeX mode)
      Shift-tab     previous tab stop  ( "  "  "   "  )
        Ctl-tab     nth tab stop       ( "  "  "   "  )
        Cmd-tab     clear tab stop     ( "  "  "   "  )
        
        Opt-tab     insert a real tab  ( "  "  "   "  )

Although the TeX-mode keybindings aren't available in Bib mode, the 
LaTeX menu is left on the menubar.  This may be useful for inserting the
various text-style codes that are recognized in BibTeX fields. 


Customizing Entry Templates
===========================

Only the required fields are included by default when a new bib entry is 
created.  You can select any other set of fields by adding an 
appropriate entry to the 'myFld' array, following the example for the 
Article entry in the file ":Modes:bibtexMode.tcl", accessible through 
the Filesets menu.

Some day I'll make it easier to customize this, but for now it's 
necessary to modify bibtex.tcl.

You should _not_ change the 'rqdFld' or 'optFld' arrays, since these 
will (some day) be used for syntax checking.


Bugs, etc.
==========

Bug reports, complaints and suggestions are very welcome.  Most of the 
improvements and bug fixes made since the last major release (2.0) were
the result of reports and suggestions from users.

Reports can be directed to the author at

     Tom Pollard	<pollard@cucbs.chem.columbia.edu>

You can also send mail to Tom Scavo (trscavo@syr.edu> or Pete Keleher 
<keleher@cs.umd.edu> and they'll forward your comments to me.

You can also send suggestions to Vince Darley <darley@fas.harvard.edu>
who has made most recent changes to bibtex mode (1997-1998).

Version History
---------------

3.0  (1/98)   Updated for Alpha 7.0, added some code for useful 
			  integration with latex mode, and with things like citation
			  completion (so you can type, in a .tex file, \cite{Smi
			  and have it extended to an entry from one of your .bib files.
2.7  (7/95)   'stdAbbrevs' modeVar added for setting predefined abbrevs
              month names included as predefined abbrevs
              'alignEquals' formatting flag added.
2.62 (7/95)   field delimiters suppressed if field data is an abbreviation
              unindexed .bib files are indexed automatically upon opening
2.61 (7/95)   fixed "SearchFields" bug.
2.6  (6/95)   'zapEmptyFields' flag forces optional fields to be removed 
                  when reformatting an entry.
              'markStrings' flag controls whether @string entries are included in 
                  the marks menu.
              'descendingYears' flag controls whether sorts are in ascending or 
                  descending chronological order.
              Sorts all use the year as either primary or secondary sort key now.
              'copyCiteKey' command copies the citekey of the current entry to the
                  clipboard.
              Cmd-double-clicking implemented to resolve abbreviations and crossrefs.
              Fixed bug in faster getFields proc (comma-after-last-field problems)  
              Fixed minor bugs in author sorting.  
2.5  (6/95)   Fixed bug in formatEntry, whereby '#' concatenations were lost 
              formatEntry completely ignores @string entries now
              Entry-parsing code (getFields, getFldVal) cleaned up,
                 should also be a little bit faster now.
              formatAllEntries now starts working from the current entry
2.41 (6/95)   Updates for compatibility with revised LaTeX mode
              Automatic conversion of international characters dropped 
                  (irreconcilable problems with non-US keyboards).
2.4  (5/95)   Fixed bugs in parsing of EndNote-created bib files
2.3  (4/95)   International characters converted to TeX codes (optionally).
              'findEntries' bug fixed (no longer returns multiple hits) 
2.2 (12/94)   'formatEntries' won't quote fields that contain "#".
              'segregateStrings' flag forces string defs to sort to the top.
2.11(12/94)   Bug fixes in 'formatAllEntries'.
2.1 (12/94)   'countEntries' command added.
              'formatAllEntries' command added; it's a bit clunky, but more robust
                  than any quicker alternative I considered.
              Cross-referenced entries now sort to the bottom in all sorts.
              'crossref' field now included.
2.0 (9/94)    'formatEntry' and 'newEntry' line up fields better.
              'nextEntry' and 'prevEntry' skip @string defs
              'formatEntry' automtically goes to next entry afterwards.
              'sortByCitekey' ignores case of cite keys.
              'fillColumn' included as default modeVar.
              'getEntry' alerts user to badly delimited entries.
1.9 (9/94)    'getFields' should now correctly parse any legal entry.
              'language' field now included.
              Default values for new fields (eg 'language') may be defined
              'preferBraces' replaced by 'fieldBraces' and 'entryBraces'.
              line-wrapping is done on reformatted entries.
              '@string' entries preserved in sorts.
              text before first entry and after last entry are preserved
                  by sorts.
1.8 (8/94)    "getEntry" now recognizes parens as entry delimiters
1.7 (8/94)    Bug fixes and accomodations to latex.tcl v2.2
              Template insertion streamlined
              Choose multiple fields at a time from a list dialog
1.6 (8/94)    "preferBraces" allows braces or quotes to be default for
                  new or reformatted entries,
              Menu built using $entryNames and $fieldNames,
              'sortByAuthors' can now sort using last author first,
                  and is a bit faster,
              'formatEntry' rewrites entries in canonical format,
              More customization of canonical format allowed ('indentString')
              Bib mode definition adapted to Alpha 5.90.
1.5 (7/94)    "sortByAuthors" is now robust,
              Mode of new windows now set correctly.
1.4 (7/94)    Added sorting by authors, but still only semi-functional,
              Added regexp searching by field,
              "getEntry" bugs fixed.
1.2 (7/94)    Bib mode definition adapted to Alpha 5.85,
              Added bib-file marking (bibMarkFile),
              Entry and field creation now controlled by data arrays.
1.1 (6/94)    Custom BibTeX icon, 
              Added simple search capability (matchingEntries).
1.0 (9/93)    First stable version.


Future Directions
-----------------

These are come of the ideas I'm considering for future enhancements to 
the BibTeX support package (roughly in the order they're likely to be 
addressed).  I welcome any comments or additional ideas people may have.

1.	Some sort of consistency and/or syntax checking of the database; for
	instance, verifying that all entries have the required fields and 
	checking for duplicate entries.

2.	Speed up entry reformatting

3.  Allowing the user to interactively choose the standard fields used 
	for a given entry type.
	
4.  Allowing more complicated searches.  Logical 'AND' searches can be 
	done now by doing additional searches on the results of previous ones.  
	It would be nice to allow logical 'OR' searches by concatenating the 
	results of successive searches to a database in the same buffer.  Ideas 
	for simple, intuitive ways to control this would be welcome.

?.  Since the code parses BibTeX entries already, it would be easy to 
	export .bib files to other formats, but I'm not sure if it's a good idea 
	to start burdening Alpha with that sort of thing.  Writing Perl scripts 
	for file conversions is probably a better idea.  See, for instance, the 
	"CC to BibTeX" Perl script (included in the :Tcl:UserCode:TextFilters 
	folder), which converts citations from the on-line Current Contents 
	database (the one at UC Berkeley, anyway) to BibTeX format.  


BibTeX application
==================

You'll probably want either Vince's port of BibTeX (available with 
OzTeX) which allows a lot of cool command-clicking in a log window
to leap to errors/warnings in your .bib files, or you may want
to use the version with CMacTeX (shareware).  
	
The original Unix version is by Oren Patashnik: BibTeX 0.99c .

Acknowledgments
===============

This package was inspired by LaTeX support package (latex.tcl), written by

   Tom Scavo          <trscavo@syr.edu>  , and (originally),
   Richard T. Austin  <austin@eecs.umich.edu>
   
---------------------------------------------------------------------------
